This note concerns the use of the Focus() method defined by ZWindow, and hence inherited by all window-type objects. Focus() is the equivalent of the toolbox SetPort() procedure, and in fact calls it- it makes the window object in question the current port, establishes the default origin and sets the initial clip region to the window's content area.
Focus() is called when necessary by the framework, for example when processing an update. There are times, however, when you may need to call Focus() yourself. This document attempts to clarify the general rules.
You may assume Focus() has been correctly called when:
a) your Draw() and/or DrawContent() method is called.
b) your Click() (or for ZScroller, ClickContent()) method is called.
c) your SetUp() method is called in ZDialog.
Focus() is NOT called when:
a) your HandleCommand() method is called, since the command dispatcher treats your window as a ZCommander, and knows nothing of graphics.
b) the Idle() method is called, for the same reason.
c) the Type() method is called.
In addition, after a message is sent using SendMessage(), the receiver of the message is legitimately permitted to change the focussed window, or even to change the settings of the current one (for example, it may change the foreground colour). Thus upon return from SendMessage(), your port is not guaranteed to be left the way it was. You can use a ZGrafState object to record and restore the entire state of the port if this is a problem.
Another pitfall is using the Idle() method to perform animation in a window, or echoing changes due to typing in the Type() method. Your overridden methods must call Focus() to ensure you draw into the correct window.
Additional information for ZScroller.
ZScroller relies (by default) on offsetting the origin of the grafPort to account for a scroll, thus your DrawContent() and ClickContent() methods can be written without needing to care about the scroll offset. It relies on the inherited Focus() method to establish the current port (which resets the origin of the port to 0, 0), but in addition provides a method for establishing the origin, called SetOriginToScroll(). In most of the cases where your code would need to call Focus() to establish the port in ZWindow, you may also need to call SetOriginToScroll() if you're using ZScroller, or you may find that your drawing, etc does not appear in the correct position within the scrollable area.
Unfocussing.
There is no Unfocus() method. Normally, objects that switch grafports are within their rights. Since Focus() is such a low-cost operation, in general you can call it then draw- all drawing objects are assumed to do this. If you require a temporary switch to another port, it is the responsibility of your code to organise this using the GetPort()/SetPort() toolbox procedures, or a ZGrafState object.
